home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_xemacs.idb / usr / freeware / lib / xemacs-20.4 / info / ph.info.z / ph.info
Encoding:
GNU Info File  |  1998-05-21  |  20.9 KB  |  531 lines
  1. This is Info file ../info/ph.info, produced by Makeinfo version 1.68
  2. from the input file ph.texi.
  3.  
  4.    This file documents ph.el v2.6
  5.  
  6.    ph.el is part of GNU Emacs.
  7.  
  8.    ph.el is an E-Lisp client interface to the CCSO white pages
  9. directory system also known as PH/QI
  10.  
  11.    Copyright (C) 1997 Free Software Foundation, Inc.
  12.  
  13.    Permission is granted to make and distribute verbatim copies of this
  14. manual provided the copyright notice and this permission notice are
  15. preserved on all copies.
  16.  
  17.    Permission is granted to copy and distribute modified versions of
  18. this manual under the conditions for verbatim copying and the terms of
  19. the "GNU General Public License", and provided that the entire
  20. resulting derived work is distributed under the terms of a permission
  21. notice identical to this one.
  22.  
  23.    Permission is granted to copy and distribute translations of this
  24. manual into another language, under the above conditions for modified
  25. versions, except that this permission notice may be stated in a
  26. translation approved by the Free Software Foundation.
  27.  
  28. 
  29. File: ph.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
  30.  
  31.    This manual documents ph.el v2.6, an E-lisp client interface to the
  32. CCSO PH/QI directory system.
  33.  
  34. * Menu:
  35.  
  36. * Introduction::                General info about the PH/QI directory system
  37. * Installation::                How to install the package
  38. * Usage::                       The various usage possibilities explained
  39. * Credits::                     Who's done what
  40. * Variables Index::
  41.  
  42. 
  43. File: ph.info,  Node: Introduction,  Next: Installation,  Prev: Top,  Up: Top
  44.  
  45. Introduction
  46. ************
  47.  
  48.    The Central Computing Services Office (CCSO) of the University of
  49. Illinois at Urbana Champaign (UIUC) created and freely distributes a
  50. directory system that is currently in use in more than 300 organizations
  51. around the world. The system records information about people such as
  52. their address, phone number, e-mail, academic information or any other
  53. details it was configured to.
  54.  
  55.    The system consists of two parts: a database server traditionally
  56. called `qi' and a command-line client called `ph'.
  57. `ftp://uiarchive.cso.uiuc.edu/pub/packages/ph' is the main distribution
  58. site.  `http://www.uiuc.edu/cgi-bin/ph/lookup?Query=.' provides a
  59. listing of the QI servers in activity.
  60.  
  61.    `ph.el' provides a client interface to this directory system letting
  62. you:
  63.  
  64.    * query the server through a customizable form
  65.  
  66.    * expand inline queries in buffers (for instance you can expand a
  67.      name to a mailing address in a mail message buffer)
  68.  
  69.    * insert server records into your own BBDB database (*note BBDB:
  70.      (bbdb)Top.)
  71.  
  72.    The original command-line `ph' client that comes with the `ph/qi'
  73. distribution provides additional features like the possibility to
  74. communicate with the server in login mode which makes it possible to
  75. change records in the database. This is not implemented in this e-lisp
  76. client.
  77.  
  78. 
  79. File: ph.info,  Node: Installation,  Next: Usage,  Prev: Introduction,  Up: Top
  80.  
  81. Installation
  82. ************
  83.  
  84.    If you are using `ph' from your GNU Emacs or XEmacs distribution you
  85. can skip this section.
  86.  
  87.    `ph' should work right out of the box with XEmacs 19.15 and above.
  88. It will not work with versions of XEmacs below.
  89.  
  90.    `ph' will work with Emacs 19.34 provided you have the `custom' and
  91. `widget' libraries by Per Abrahmsen installed. You can get them from
  92. `http://www.dina.kvl.dk/~abraham/custom/'
  93.  
  94.    When installing `ph' yourself you should move `ph.el' to a proper
  95. directory in your `load-path' and byte-compile it (see the section on
  96. byte-compilation in your users manual if you do not know what that
  97. means). Install `ph.info' into a directory where the info system can
  98. find it or update your `Info-default-directory-list' variable.
  99.  
  100.    Then you can add the following into your `.emacs' startup file:
  101.      (require 'ph)
  102.      (eval-after-load
  103.       "message"
  104.       '(define-key message-mode-map [(control ?c) (tab)] 'ph-expand-inline))
  105.      (eval-after-load
  106.       "mail"
  107.       '(define-key mail-mode-map [(control ?c) (tab)] 'ph-expand-inline))
  108.  
  109.    Upon starting a new session you will find a new `Ph' sub-menu in the
  110. `Tools' menu that will let you access all the interesting `ph'
  111. functions.
  112.  
  113. 
  114. File: ph.info,  Node: Usage,  Next: Credits,  Prev: Installation,  Up: Top
  115.  
  116. Usage
  117. *****
  118.  
  119.    This chapter describes the usage of `ph.el'. Most functions are
  120. available through the `Ph' sub-menu of the `Tools' sub-menu.
  121.  
  122. * Menu:
  123.  
  124. * Querying QI Servers::         How queries are performed and handled
  125. * Query Form::                  How to use and customize the query form
  126. * Inline Query Expansion::      How to use and customize inline queries
  127. * Creating BBDB Records::       How to insert query results into your BBDB
  128. * The Server Hotlist::          How to use and manage the server hotlist
  129.  
  130. 
  131. File: ph.info,  Node: Querying QI Servers,  Next: Query Form,  Prev: Usage,  Up: Usage
  132.  
  133. Querying Servers
  134. ================
  135.  
  136.    `ph' basic functionality is to let you query a QI server and return
  137. the results back to you. There are several things you may want to
  138. customize in this process.
  139.  
  140. * Menu:
  141.  
  142. * Selecting a Server::          The first thing to do
  143. * Return Fields::               How to configure query results
  144. * Handling Duplicate Fields::   What to do when records have duplicate fields
  145.  
  146. 
  147. File: ph.info,  Node: Selecting a Server,  Next: Return Fields,  Prev: Querying QI Servers,  Up: Querying QI Servers
  148.  
  149. Selecting a Server
  150. ------------------
  151.  
  152.    Before doing any query you will need to set the query server, this is
  153. the name of the host machine running the `qi' software. If you do not
  154. set it in any fashion, `ph' will ask you for one when you make your
  155. first query.
  156.  
  157.  - Variable: ph-server
  158.      The name or IP address of the CCSO (PH/QI) server. A port number
  159.      may be specified by appending a colon and a number to the name of
  160.      the server. You will not need this unless your server runs on
  161.      different port than the usual 105.
  162.  
  163. 
  164. File: ph.info,  Node: Return Fields,  Next: Handling Duplicate Fields,  Prev: Selecting a Server,  Up: Querying QI Servers
  165.  
  166. Return Fields
  167. -------------
  168.  
  169.    `qi' servers are configured to return a default set of fields for
  170. each record matching a query if the query specifies none. The variable
  171. `ph-default-return-fields' controls the return fields you want for your
  172. queries.
  173.  
  174.  - Variable: ph-default-return-fields
  175.      A list of the default fields to extract from CCSO entries.  If it
  176.      contains `all' then all available fields are returned. `nil' means
  177.      return the default fields as configured in the server. Default is
  178.      `nil'
  179.  
  180.    The server may return several matching records to a query. Some of
  181. the records may however not contain all the fields you requested. You
  182. can chose to discard those records.
  183.  
  184.  - User Option: ph-strict-return-matches
  185.      If non-`nil', entries that do not contain all the requested return
  186.      fields are ignored.  Default is `t'.
  187.  
  188. 
  189. File: ph.info,  Node: Handling Duplicate Fields,  Prev: Return Fields,  Up: Querying QI Servers
  190.  
  191. Handling Duplicate Fields
  192. -------------------------
  193.  
  194.    `qi' authorizes records to have different instances of the same
  195. field. For instance the record of a person may contain several e-mail
  196. fields containing different e-mail addresses. This is difficult to
  197. distinguish from fields having multi-line values such as the postal
  198. address that may contain a line for the street and another one for the
  199. zip code and city name. In both cases, `ph' considers the field be
  200. duplicated.
  201.  
  202.    `ph' has several methods to deal with duplicate fields. The
  203. available methods are:
  204.  
  205. `list'
  206.      Makes a list with the different values of the duplicate field. The
  207.      record keeps only one instance of the field the value of which is
  208.      a list of all the different values. This is the default method
  209.      that is used to handle duplicate fields for which no other method
  210.      has been specified.
  211.  
  212. `first'
  213.      Discards all the duplicate values of the field keeping only the
  214.      first one.
  215.  
  216. `concat'
  217.      Concatenates the different values using `\n' as a separator. The
  218.      record keeps only one instance of the field the value of which is a
  219.      single multi-line string.
  220.  
  221. `duplicate'
  222.      Duplicates the whole record into as many instances as there are
  223.      different values for the field. This is the default for the e-mail
  224.      field. Thus a record containing 3 different e-mail addresses is
  225.      duplicated into three different records each having a single
  226.      e-mail address. This is particularly useful in combination with
  227.      `select' as the method to handle multiple matches in inline
  228.      expansion queries (*note Inline Query Expansion::.) because you
  229.      are presented with the 3 addresses in a selection buffer
  230.  
  231.    Because a method may not be applicable to all fields, the variable
  232. `ph-duplicate-fields-handling-method' lets you specify either a default
  233. method for all fields or a method for each individual field.
  234.  
  235.  - Variable: ph-duplicate-fields-handling-method
  236.      A method to handle entries containing duplicate fields.  This is
  237.      either an alist (FIELD . METHOD) or a symbol METHOD.  The alist
  238.      form of the variable associates a method to an individual field,
  239.      the second form specifies a method applicable to all fields.
  240.      Available methods are: `list', `first', `concat', `duplicate'
  241.      duplicates the entire entry into as many instances as different
  242.      values.  Defaults to `list'.
  243.  
  244. 
  245. File: ph.info,  Node: Query Form,  Next: Inline Query Expansion,  Prev: Querying QI Servers,  Up: Usage
  246.  
  247. Query Form
  248. ==========
  249.  
  250.    The simplest way to query your directory server is to use the query
  251. form. You display the query form with the `Query Form' menu item or by
  252. typing `M-x ph-query-form'. The fields presented in this form are
  253. defined by the `ph-form-fields' variable (unless a non-`nil' argument
  254. is supplied to `ph-query-form').
  255.  
  256.  - Variable: ph-form-fields
  257.      A list of fields presented in the query form. You can get a list of
  258.      valid field names with the `List Valid Field Names' menu item or
  259.      `M-x ph-get-field-list'. Defaults to `name', `email' and `phone'.
  260.  
  261.  - Command: ph-query-form GET-FIELDS-FROM-SERVER
  262.      Display a form to query the CCSO PH/QI Nameserver.  If given a
  263.      non-nil argument the function first queries the  server for the
  264.      existing fields and displays a corresponding form.
  265.  
  266.    Since the names of the fields may not be explicit enough or adapted
  267. to be directly displayed as prompt strings in the form, the variable
  268. `ph-fieldname-formstring-alist' lets you define prompt strings for the
  269. various fields.
  270.  
  271.  - Variable: ph-fieldname-formstring-alist
  272.      This is an alist mapping CCSO database field names onto prompt
  273.      strings used in query/response forms. Prompt strings for fields
  274.      that are not in this alist are derived by replacing underscores
  275.      with spaces and capitalizing the individual words.
  276.  
  277.    Upon successful completion the command will display a buffer
  278. containing the results of the query. The fields that are returned for
  279. each record are controlled by `ph-default-return-fields' (*note Return
  280. Fields::.)
  281.  
  282. 
  283. File: ph.info,  Node: Inline Query Expansion,  Next: Creating BBDB Records,  Prev: Query Form,  Up: Usage
  284.  
  285. Inline Query Expansion
  286. ======================
  287.  
  288.    Instead of using a query form, you may prefer inline expansion. This
  289. is a powerful method to get completion from your directory server. The
  290. most common usage is for expanding names to e-mail addresses in mail
  291. message buffers. The expansion is performed by the command
  292. `ph-expand-inline'. The operation is controlled by the variables
  293. `ph-inline-expansion-format', `ph-inline-query-format-list',
  294. `ph-expanding-overwrites-query' and `ph-multiple-match-handling-method'
  295.  
  296.  - Command: ph-expand-inline REPLACE-P
  297.      Query the server and expand the query string before point.  The
  298.      query string consists of the buffer substring from the point back
  299.      to the preceding comma, colon or beginning of line. If it consists
  300.      of more than one word the variable `ph-inline-query-format-list'
  301.      controls how these are mapped onto CCSO database field names.
  302.      After querying the server for the given string, the expansion
  303.      specified by `ph-inline-expansion-format' is inserted in the
  304.      buffer at point. If REPLACE-P is `t' then this expansion replaces
  305.      the query string in the buffer.  If
  306.      `ph-expanding-overwrites-query' is non-`nil' then the meaning of
  307.      REPLACE-P is negated.
  308.  
  309.  - Variable: ph-inline-query-format-list
  310.      Format of an inline expansion query.  If the inline query string
  311.      consists of several words, this list specifies how these individual
  312.      words are associated to CCSO database field names.  If `nil' all
  313.      the words will be mapped onto the default CCSO database key
  314.      (generally `name'). Default is `nil'.
  315.  
  316.  - Variable: ph-inline-expansion-format
  317.      This variable lets you control what is exactly inserted into the
  318.      buffer upon an inline expansion request. It is a list whose first
  319.      element is a string passed to `format'. Remaining elements are
  320.      symbols corresponding to CCSO database field names, corresponding
  321.      field values are passed as additional arguments to format. Default
  322.      is `("%s" email)' but you may want to consider a value like `("%s
  323.      <%s>" name email)'
  324.  
  325.  - Variable: ph-multiple-match-handling-method
  326.      This variable controls what to do when multiple entries match a
  327.      query for an inline expansion.  Possible values are:
  328.     `first'
  329.           The first match is considered as being the only one, the
  330.           others are discarded.
  331.  
  332.     `select'
  333.           A selection buffer pops-up where you can choose a particular
  334.           match. This is the default value of the variable.
  335.  
  336.     `all'
  337.           The expansion uses all records successively
  338.  
  339.     `abort'
  340.           An error is signaled. The expansion aborts.
  341.  
  342.      Defaults to `select'
  343.  
  344. 
  345. File: ph.info,  Node: Creating BBDB Records,  Next: The Server Hotlist,  Prev: Inline Query Expansion,  Up: Usage
  346.  
  347. Creating BBDB Records
  348. =====================
  349.  
  350.    With `ph', you can automatically create BBDB records (*note BBDB:
  351. (bbdb)Top.) from records you get from a PH/QI server. You do this by
  352. moving the point to the appropriate record in a query result display
  353. buffer and invoking the command `ph-insert-record-at-point-into-bbdb'
  354. with the corresponding keyboard binding, `b' (1) or with the menu. `ph'
  355. cannot update an existing BBDB record and will signal an error if you
  356. try to insert a record matching an existing one.
  357.  
  358.    Because the CCSO directory system does not enforce a strict record
  359. format, local installations of the QI server use different names for the
  360. record fields and have different ways to organize the information.
  361. Furthermore BBDB has its own record structure that has little to do
  362. with what is commonly found on QI servers. For these reasons the
  363. process of converting a record from its QI format to the BBDB format is
  364. highly customizable.
  365.  
  366.  - Variable: ph-bbdb-conversion-alist
  367.      This is the variable that lets you customize how BBDB fields map to
  368.      PH/QI records. Its value is an alist of cells of the form
  369.      `('BBDB-FIELD . SPEC-OR-LIST`)'. BBDB-FIELD is the name of a field
  370.      that must be defined in your BBDB environment (standard field
  371.      names are `name', `company', `net', `phone', `address' and
  372.      `notes'). SPEC-OR-LIST is either a single mapping specification or
  373.      a list of mapping specifications. Lists of mapping specifications
  374.      are valid for the `phone' and `address' BBDB fields only. SPECs
  375.      are actually s-expressions which are evaluated as follows:
  376.  
  377.     a string
  378.           evaluates to itself
  379.  
  380.     a symbol
  381.           evaluates to the symbol value. Symbols corresponding to PH/QI
  382.           fields present in the record evaluate to the value of the
  383.           field in the record
  384.  
  385.     a form
  386.           is evaluated as a function. The argument list may contain
  387.           PH/QI field names which evaluate to the corresponding values
  388.           in the record. The form evaluation should return something
  389.           appropriate for the particular BBDB-FIELD (see
  390.           `bbdb-create-internal').  `ph-bbdbify-phone' and
  391.           `ph-bbdbify-address' are provided as convenience functions to
  392.           parse phones and addresses.
  393.  
  394.    The default value of `ph-bbdb-conversion-alist' is:
  395.  
  396.      ((name . name)
  397.       (net . email)
  398.       (address . (ph-bbdbify-address address "Address"))
  399.       (phone . ((ph-bbdbify-phone phone "Phone")
  400.                 (ph-bbdbify-phone office_phone "Office Phone"))))
  401.  
  402.    This means that:
  403.  
  404.    * the `name' field of the BBDB record gets its value from the `name'
  405.      field of the PH/QI record
  406.  
  407.    * the `net' field of the BBDB record gets its value from the `email'
  408.      field of the PH/QI record
  409.  
  410.    * the `address' field of the BBDB record is obtained by parsing the
  411.      `address' field of the PH/QI record with the function
  412.      `ph-bbdbify-address'
  413.  
  414.    * two `phone' fields are created (when possible) in the BBDB record.
  415.      The first one has "Phone" for location and its value is obtained by
  416.      parsing the `phone' field of the PH/QI record with the function
  417.      `ph-bbdbify-phone'. The second one has "Office Phone" for location
  418.      its value is obtained by parsing the `office_phone' field of the
  419.      PH/QI record with the function `ph-bbdbify-phone'.
  420.  
  421.  - Function: ph-bbdbify-phone PHONE LOCATION
  422.      This is a convenience function provided for use in
  423.      `ph-bbdb-conversion-alist'. It parses PHONE into a vector
  424.      compatible with `bbdb-create-internal'. PHONE is either a string
  425.      supposedly containing a phone number or a list of such strings
  426.      which are concatenated. LOCATION is used as the phone location for
  427.      BBDB.
  428.  
  429.  - Function: ph-bbdbify-address ADDR LOCATION
  430.      This is a convenience function provided for use in
  431.      `ph-bbdb-conversion-alist'. It parses ADDR into a vector
  432.      compatible with `bbdb-create-internal'. ADDR should be an address
  433.      string of no more than four lines or a list of lines. The last
  434.      line is searched for the zip code, city and state name. LOCATION
  435.      is used as the phone location for BBDB.
  436.  
  437.    Note that only a subset of the fields you selected with
  438. `ph-default-return-fields' and that are actually displayed may actually
  439. be inserted as part of the newly created BBDB record.
  440.  
  441.    ---------- Footnotes ----------
  442.  
  443.    (1) This keybinding does not actually call
  444. `ph-insert-record-at-point-into-bbdb' but uses `ph-try-bbdb-insert'
  445. instead.
  446.  
  447. 
  448. File: ph.info,  Node: The Server Hotlist,  Prev: Creating BBDB Records,  Up: Usage
  449.  
  450. The Server Hotlist
  451. ==================
  452.  
  453.    `ph' lets you maintain a list of frequently used servers so that you
  454. can easily switch from one to another. This hotlist appears in the
  455. `Server' sub-menu. You select a server in this list by clicking on its
  456. name. You can add the current server to the list with the command
  457. `ph-bookmark-current-server'. The list is contained in the variable
  458. `ph-server-hotlist' which is stored in and retrieved from the file
  459. designated by `ph-options-file'.
  460.  
  461.  - Command: ph-bookmark-server SERVER
  462.      Add SERVER to the hotlist of servers
  463.  
  464.  - Command: ph-bookmark-current-server
  465.      Add the current server to the hotlist of servers
  466.  
  467.  - Variable: ph-options-file
  468.      The name of a file where `ph' stores its internal variables
  469.      (currently only the hotlist is stored there). `ph' will try to load
  470.      that file upon initialization so, if you choose a file name
  471.      different from the defaults `~/.ph-options', be sure to set this
  472.      variable to the appropriate value *before* `ph' is itself loaded.
  473.  
  474.    There is currently no way to remove a server from the list other than
  475. editing directly the `ph-options-file'.
  476.  
  477. 
  478. File: ph.info,  Node: Credits,  Next: Variables Index,  Prev: Usage,  Up: Top
  479.  
  480. Credits
  481. *******
  482.  
  483.    The original CCSO Nameserver software (`ph' & `qi') was written at
  484. the University of Illinois at Urbana Champaign.
  485.  
  486.    The Emacs client `ph.el' was written and is maintained by Oscar
  487. Figueiredo.
  488.  
  489.    Thanks to Soren Dayton for his suggestions, his enthusiasm and his
  490. help in testing and proofreading the code and docs.
  491.  
  492. 
  493. File: ph.info,  Node: Variables Index,  Prev: Credits,  Up: Top
  494.  
  495. Variables Index
  496. ***************
  497.  
  498. * Menu:
  499.  
  500. * ph-bbdb-conversion-alist:              Creating BBDB Records.
  501. * ph-default-return-fields:              Return Fields.
  502. * ph-duplicate-fields-handling-method:   Handling Duplicate Fields.
  503. * ph-fieldname-formstring-alist:         Query Form.
  504. * ph-form-fields:                        Query Form.
  505. * ph-inline-expansion-format:            Inline Query Expansion.
  506. * ph-inline-query-format-list:           Inline Query Expansion.
  507. * ph-multiple-match-handling-method:     Inline Query Expansion.
  508. * ph-options-file:                       The Server Hotlist.
  509. * ph-server:                             Selecting a Server.
  510. * ph-strict-return-matches:              Return Fields.
  511.  
  512.  
  513. 
  514. Tag Table:
  515. Node: Top1049
  516. Node: Introduction1515
  517. Node: Installation2930
  518. Node: Usage4234
  519. Node: Querying QI Servers4826
  520. Node: Selecting a Server5321
  521. Node: Return Fields5977
  522. Node: Handling Duplicate Fields6951
  523. Node: Query Form9459
  524. Node: Inline Query Expansion11138
  525. Node: Creating BBDB Records13936
  526. Node: The Server Hotlist18551
  527. Node: Credits19784
  528. Node: Variables Index20204
  529. 
  530. End Tag Table
  531.